As tell-dont-ask implies we expect creation of the operation, edge cases could lead to clear exceptions on how to resolve those. What about dropping nullability on the return typehint, and throw LogicException here?

+1 and then remove the lines at:

https://github.com/api-platform/core/pull/7595/files/b904a0d0b94bc53bd5e701c7a1eb456ca255ae5c

What about letting all these classes extend a Resource interface, and solely register the tag on that class? Or even better; consider the FQCN of that interface as the tag? Interface composition would be great way to document behaviors.

They all extend Metadata but I like this descriptive approach (not sure it works with a parent class also I'd need to check).
Not sure I understand the use of the fqcn tag as a namespace but we could easily add it!

Putting the #[AutoconfigureTag(Resource::class)] on such a "parent" Resource interface will register all implementation with FQCN as the tag on the container. Even the ones that extend a child interface. One of Symfony container's superpowers if you ask me.

If the functional goal for you would be to have all resource implementations available (probably somewhere later in a compiler pass?), then tagging them with the class name makes it possible to wire the entire collection of implementations with a single #[AutowireIterator(Resource::class)] attribute where needed.

class McpTool extends HttpOperation implements Resource { }

/**
 * Extensive documentation about what Resource functionally is about....
 */
#[AutoconfigureTag(self::class)]
interface Resource {}

class ResourceCompilerPass {
	public function __construct(
		#[AutowireIterator(Resource::class)]
		private iterable $resources
	) { } 
}

To me, tagging with a FQCN is more descriptive as tagging with a simple textual tag, as it allows a single-click navigation to that interface in the IDE. The interface's documentation should then be descriptive enough to explain the rationales behind the interface segregation.

And, not having the foreach here also lowers maintenance efforts. There is no need for the entire foreach, and adding an extra type of resource then instantly makes them available in that potential compiler pass I'm referring to above as well.

Putting the #[AutoconfigureTag(Resource::class)] on such a "parent" Resource interface will register all implementation with FQCN as the tag on the container. Even the ones that extend a child interface. One of Symfony container's superpowers if you ask me.

Yes but bundles can not use attributes for dependency injection but indeed this is a good point for DX.

👍 about the code you shared we should definitely do this and try to remove https://github.com/api-platform/core/blob/main/src/Metadata/Util/ReflectionClassRecursiveIterator.php. But this is another job that already started with #6943 btw

Is the tool really the operation? Feels like there should be something in the middle of tool handling as well, to allow (like the symfony ai implementations) dispatch specific events around the handling.

I don't understand could you point me to some code or the component responsible of this?

The feeling comes from Symfony Conference's "Symfony AI in Action" keynote that Christopher Hertel gave. https://live.symfony.com/account/replay/video/1128

Of course it eventually are the processors / providers that allow users to do what's needed, so I'm mostly referring to the lifecycle of such a MCP tool.

https://symfony.com/doc/current/ai/components/agent.html#tool-call-lifecycle-events

Hooking into the way how things are or are not propagated seems valuable, for instance with regards to continuing code execution or not? But, maybe the Symfony events referenced to above are sufficient?

Agent tools (AsTool) and MCP (McpTool) are different things in the symfony/ai ecosystem, they don't interacts with Tool from MCP AFAIK (btw funny that they also use strings for tags, quite a convention for bundles: https://github.com/symfony/ai/blob/e885dbfab6115a89e6118fcc4d5dbe3567a72681/src/ai-bundle/src/AiBundle.php#L339)